home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / rbbsdocs.zip / RBBSDOCS.7 < prev    next >
Text File  |  1990-11-05  |  89KB  |  1,892 lines
  1.  
  2.  
  3.  
  4.     PLANNING YOUR USER INTERFACE                                            7-1
  5.  
  6.  
  7.     7. PLANNING YOUR USER INTERFACE
  8.     --------------------------------
  9.     RBBS-PC provides each SysOp the  maximum control over what is  presented to
  10.     callers.  There are three areas of control:
  11.  
  12.        - The menus presented to novice callers.
  13.        - What is included in the prompt all users get.
  14.        - What symbol invokes a particular function.
  15.  
  16.     7.1 Menus Shown to Callers
  17.     --------------------------
  18.     The menus in  RBBS-PC are external text files that  are presented to novice
  19.     users.   RBBS-PC simply displays  what is  in these files  to the  callers.
  20.     Therefore, SysOps  are free to change  the text in these  files to whatever
  21.     they  desire.  Simply  edit the files.   However, be sure  to use an editor
  22.     that  produces only ASCII text  files with no  special embedded characters.
  23.     Most word processing editors  are not suitable because they  insert special
  24.     symbols in the file meaningful only to it.  Menus can also contain graphics
  25.     and color (see section 6.3).
  26.  
  27.     7.2 Subsystem Prompts Shown to Callers
  28.     --------------------------------------
  29.     RBBS-PC  has several configuration options which allow each SysOp to select
  30.     the prompts that are presented to callers.  They are:
  31.  
  32.        - Whether the section name is displayed.
  33.        - Whether the letters of the available commands are shown.
  34.  
  35.     The  commands  in RBBS-PC  are  divided into  four  sections:   MAIN, FILE,
  36.     UTILITY and LIBRARY.  If RBBS-PC is configured to display the section name,
  37.     the command prompt will read "<section> command", otherwise "Your command".
  38.     The section name is shown by default.
  39.  
  40.     RBBS-PC  normally prompts  a  caller  with  the  commands  the  caller  has
  41.     sufficient  security to  invoke.  Each  command is  a single  letter and is
  42.     shown separated from  the others by a  comma.  The  command letters can  be
  43.     suppressed in the prompt.  By leaving them on a  SysOp provides each caller
  44.     with a terse but helpful reminder of what commands are available to them.
  45.  
  46.     7.3 Commands Available to Callers
  47.     ---------------------------------
  48.     All primary commands in RBBS-PC are  invoked by single letter commands.  An
  49.     attempt  is made to associate  the command with the first  letter in a word
  50.     which describes  the function, so that  the command letter appears  to be a
  51.     short abbreviation  for the longer  word.   The command  to invoke  reading
  52.     messages is R.  The default symbols that would be shown in the command line
  53.     for each section are:
  54.  
  55.     sect |? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y 1 2 3 4 5 6 7
  56.     -----|-------------------------------------------------------------------
  57.     MAIN |? @ A B C D E F   H I J K       O P Q R S T   V W X   1 2 3 4 5 6 7
  58.          |
  59.     FILE |?         D     G H       L   N   P Q   S   U V   X
  60.          |
  61.     UTIL |?     B C   E F G H       L M     P Q R S T U     X
  62.          |
  63.     LIB  |?   A   C D     G H       L         Q   S     V   X
  64.          |
  65.     GLBL |?                 H                 Q             X
  66.  
  67.  
  68.  
  69.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                     7-2
  70.  
  71.  
  72.     Four commands, ? H  Q and X, have the same meaning in every section and are
  73.     known as "global."   The other commands  all have unique function  specific
  74.     for the section within which they  are invoked.  For example, S  stands for
  75.     S)can messages in  MAIN, S)earch  in FILE and  LIBRARY, and S)tatistics  in
  76.     UTIL.  Symbols 1-7 are used for SysOp functions.
  77.  
  78.     RBBS-PC allows the SysOp to  substitute any symbol for any command.   Y)ell
  79.     may  be substituted for O)perator  page, or Y)our  mail for P)ersonal mail.
  80.     If a blank  is substituted, the command is removed from  the list and is no
  81.     longer available.
  82.  
  83.     7.4 RBBS-PC's "Wrap-around" Command Search
  84.     ------------------------------------------
  85.     There  is an option in CONFIG which  gives the SysOp unusual flexibility in
  86.     configuring  the  user  interface.   A  caller  is always  "in"  a section.
  87.     RBBS-PC considers the user's current section  when acting on commands.  The
  88.     "wrap  around" option allows RBBS-PC to look  further for a command when it
  89.     is  not found in the  section the caller  is in.  If  a SysOp substitutes a
  90.     blank for the V>iew conference command in the main section (as mentioned in
  91.     section  7.3) and a user  enters the V  command from the  main section, the
  92.     V)iew archive file command would be what the caller would have invoked.
  93.  
  94.     The fundamental idea is to look further in other sections, where the search
  95.     order is circular,  starting at the current section,  and proceeding in the
  96.     following order:
  97.  
  98.                -MAIN->FILE->UTIL->LIBRARY->GLOBAL->SYSOP-
  99.               |                                          |
  100.                -------------------<----------------------
  101.  
  102.     If wrap-around is used, RBBS-PC will search ALL sections, in order, to find
  103.     a valid command that matches the user's input.  Even if  wrap-around is not
  104.     used, GLOBAL and SYSOP commands are processed globally.
  105.  
  106.     The important feature that  wrap-around supports is  that a command with  a
  107.     unique letter  works in all  sections.  Thus  W)ho will work  everywhere if
  108.     wrap-around is enabled.  If every RBBS-PC command is given a unique symbol,
  109.     all commands become  global and  there is no  effective difference  between
  110.     sections.  This allows SysOps to  make commands available on a single level
  111.     and  makes it unnecessary  to "go" to  a section before  using a command in
  112.     that section.
  113.  
  114.     7.5 How to Have a Single Universal Command Line
  115.     ------------------------------------------------
  116.     The command structure within  RBBS-PC can be made "flatter"  without making
  117.     it absolutely flat.  Suppose, for example, that a SysOp wants callers to be
  118.     able to do all file functions without going to a files section.  In effect,
  119.     the file functions  are available in the main section,  or the file section
  120.     is merged into the main  section.  To do this, the SysOp must eliminate the
  121.     overlap in command letters between the two sections.
  122.  
  123.     The main section and the file section share the letters D, P, S, and V.   V
  124.     is used  to "view"  a conference in  the main  section and  "view" what  is
  125.     contained in  an archived  file.   D is difficult  because both  D)oors and
  126.     D)ownload are  entrenched and natural options.   One could leave  D for the
  127.     most  frequently  used  function, say  download,  then  use  a special  but
  128.     arbitrary symbol like # for doors.   Similarly, V could be left for viewing
  129.     conference mail in the main section and a special but arbitrary symbol like
  130.     &  for viewing archived files in the  file section.  S)earch for substrings
  131.  
  132.  
  133.  
  134.     PLANNING YOUR USER INTERFACE                                            7-3
  135.  
  136.  
  137.     could be replaced by F)ind since F for going to F)iles is no longer needed.
  138.     This could be accomplished by disabling F)iles and substituting F  for S in
  139.     the files commands.
  140.  
  141.     P  is used for personal mail in the  main section as well as personal files
  142.     in the file section.   Leaving P in the main section for  personal mail and
  143.     selecting the symbol M for personal mail in the file section would have the
  144.     least impact on callers.
  145.  
  146.     U is used for upload.  Since Quit may be used to go to UTIL, we can disable
  147.     U in the main menu.  We can use W for W)rite user preferences and F to find
  148.     who  else is on (since  the F for  FILES section is no  longer needed).  We
  149.     could then revise the main menu to read:
  150.  
  151.                           R B B S   M A I N   M E N U
  152.                           ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  153.     [A]nswer survey [H]elp (or ?)     [P]ersonal mail   [U]pload a file
  154.     [B]ulletins     [I]nitial welcome [$]Personal files [V]iew conference mail
  155.     [C]omments      [J]oin conference [Q]uit            [&]View ARC files
  156.     [#]DOORS        [K]ill message    [R]ead messsages  [W]rite user pref
  157.     [D]ownload      [L]ist files      [S]can messages   [X]pert on/off
  158.     [E]nter msg     [N]ew files       [T]opic msg scan  [Z]ippy search
  159.     [F]ind who's on [O]perator page                     [@]Library
  160.     [G]oodbye
  161.  
  162.     Obviously the limitations of  using a single section (as the more primitive
  163.     bulletin  board systems  do)  means that  the number  of  commands must  be
  164.     restricted to either
  165.  
  166.        - 26 (letters in the alphabet), or
  167.        - 36 (letters in the alphabet plus the numbers 0 through 9), or
  168.        - full "words".
  169.  
  170.     With  this  artificial limitation  of  a  single  section, commands  become
  171.     limited in  number, cryptic, or both.  If the  even more clumsy use of full
  172.     "words"  is chosen,  the system  must slow  down as  it can  no  longer act
  173.     immediately upon seeing the first character of a command as RBBS-PC does.
  174.  
  175.     However,  assuming that someone would actually want to configure RBBS-PC to
  176.     be "flat" (i.e. have a single command line), let us continue.  In order not
  177.     to confuse the  caller by being in  a section and  seeing only some of  the
  178.     commands we want him to  use, the SysOp could elect not to show the section
  179.     in the  prompt (CONFIG parameter 37)  and not to show  the commands (CONFIG
  180.     parameter  38). Callers  would see  simply "Your  command?" as  the prompt.
  181.     This makes the  expert mode quite terse, but that  simply means users would
  182.     spend more time in novice mode before using expert.
  183.  
  184.     Now  suppose that  only a  single  command line  was desired  and that  the
  185.     commands from the "Utilities" menu commands were to be added to the above.
  186.     The "global"  H, ?, Q,  and X  commands already are  in the single  command
  187.     line.
  188.  
  189.     M  for  message margin  can  remain unchanged  since  it is  unique  to the
  190.     Utilities subsystem.
  191.  
  192.     In  order to accommodate the redundancy  of letters that exist by including
  193.     the  Utilities subsystem's  commands, the  W command  for the  main message
  194.     subsystem can be re-enabled and the remote SysOps commands be eliminated in
  195.     order to re-use  the numbers.  The Utilities subsystem commands B, C, F, G,
  196.  
  197.  
  198.  
  199.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                     7-4
  200.  
  201.  
  202.     L,  R, and  S could  then be  replaced by  the numbers  1  through 9.   The
  203.     Utilities subsystem  commands T,  U,  E, and  P could  be  replaced by  the
  204.     commands <, >, \, and !, respectively.
  205.  
  206.     This final  menu of all  RBBS-PC commands  could be re-written  without any
  207.     apparent  sub-sections as follows  and the screen that  the would appear to
  208.     the "novice" users as:
  209.  
  210.                           R B B S  C O M M A N D S
  211.                           ~~~~~~~~~~~~~~~~~~~~~~~~
  212.     [A]nswer survey    [O]perator page        [1] Change Baud Rate 300-->450
  213.     [B]ulletins        [$]Personal files      [2] Display time of day
  214.     [C]omments         [P]ersonal mail        [3] Set file transfer protocol
  215.     [#]DOORS           [Q]uit                 [4] Set type of graphics mode
  216.     [D]ownload         [R]ead messages        [5] Set page length
  217.     [E]nter msg        [S]can messages        [8] Review callers preferences
  218.     [G]oodbye          [T]opic msg scan       [9] Display system statistics
  219.     [H]elp (or ?)      [U]pload a file        [<] Toggle users options on/off
  220.     [I]nitial welcome  [V]iew conference mail [>] Show the log of callers
  221.     [J]oin conference  [&]View ARC files      [@] Library
  222.     [K]ill message     [W]ho's on other nodes [\] Change echo selection
  223.     [L]ist files       [X]pert on/off         [!] Change password
  224.     [M]argin set       [Z]ippy search
  225.     [N]ew files
  226.  
  227.     Your command?
  228.  
  229.     7.6 RBBS-PC'S Programmable User Interface (PUI)
  230.     -----------------------------------------------
  231.     The  programmable user interface (PUI,  pronounced "pee you  eye") lets the
  232.     SysOp take TOTAL CONTROL over what the caller is presented with, including:
  233.  
  234.        - the novice menu
  235.        - the prompt line
  236.        - the organization of commands into groups (sections)
  237.        - the flow between sections
  238.        - unlimited levels of nested menus.
  239.  
  240.     This  allows the  RBBS-PC interface  that the  caller sees  to take  on any
  241.     appearance desired  by the SysOp.  In effect, the  SysOp is limited only by
  242.     the intrinsic functions of  RBBS-PC that have been programmed  into RBBS-PC
  243.     source code.  These functions can be assigned any command letter desired in
  244.     CONFIG.   PUI  lets the  SysOp completely  control how  these commands  are
  245.     presented to the user  - allowing RBBS-PC to "emulate" virtually  any other
  246.     host communications  environment that the  SysOp's callers may  be familiar
  247.     with.
  248.  
  249.     If no  PUI is provided,  RBBS-PC defaults to  dividing the commands  into a
  250.     MAIN, FILES, UTILITIES, and LIBRARY section.
  251.  
  252.     RBBS-PC's PUI gives  each SysOp the  flexibility to tailor RBBS-PC  to meet
  253.     special needs.  In effect, RBBS-PC's PUI allows the SysOp to adjust RBBS-PC
  254.     to what  the SysOp wants, rather than forcing the  SysOp and his callers to
  255.     conform to RBBS-PC.
  256.  
  257.     However, unlike  RBBS-PC, the PUI does  not adjust the prompt  to show only
  258.     the commands that the user has sufficient  security to do.  And, of course,
  259.     PUI takes much more time to design and implement.
  260.  
  261.  
  262.  
  263.     PLANNING YOUR USER INTERFACE                                            7-5
  264.  
  265.  
  266.     When  the SysOp takes  control of what  the user is  presented by using the
  267.     PUI, RBBS-PC does what the SysOp has explicitly set up -- and nothing else!
  268.     For  example, RBBS-PC's "global" commands, like help and the expert toggle,
  269.     are  no longer automatically available everywhere.  They are available only
  270.     where the SysOp has indicated via the PUI.
  271.  
  272.     RBBS-PC's  default user interface has  evolved over the  years to represent
  273.     what the callers found useful (not the SysOps!).   A great deal of time and
  274.     thought went  into RBBS-PC's  default user  interface, and  it  is easy  to
  275.     overlook  important things when  a SysOp goes  about setting up  his or her
  276.     own.  When using the PUI assume that a new user interface will take time to
  277.     both develop  and refine (based  on your callers feedback).   Designing and
  278.     implementing a PUI is not a simple undertaking as it is a total replacement
  279.     for RBBS-PC's standard user interface.
  280.  
  281.     7.6.1 An Example Using PUI
  282.     --------------------------
  283.     The main  menu in RBBS-PC can represent  a bewildering variety of commands,
  284.     especially to a new user.   Studies show that human beings  can effectively
  285.     deal with at most 7  choices at one time, whereas RBBS-PC has  10 more than
  286.     that in its main section.  To help  people in this situation, the different
  287.     choices in RBBS-PC are  grouped into related commands, but the  choices can
  288.     still be overwhelming.  Some SysOps have tried to simplify the main menu by
  289.     breaking it up into more sections.  The most tempting  group of commands to
  290.     spin  off  are  the message  commands.   Suppose  the  main menu  is  to be
  291.     simplified to look like:
  292.  
  293.          <F>iles
  294.          <M>ail
  295.          <U>ser preferences
  296.          <G>oodbye
  297.  
  298.     The <M>ail command  puts the caller in a section  where commands related to
  299.     messages become  available in yet  another menu, such as  J)oin and E)nter.
  300.     PUI is required because  the commands are grouped into  different sections.
  301.     While  the  default menu  of  RBBS-PC  could be  edited  to  say this,  the
  302.     underlying commands would not be grouped as desired.
  303.  
  304.     7.6.2 How to Implement PUI
  305.     --------------------------
  306.     First, plan carefully on  paper exactly what you want the caller to see and
  307.     what happens with each command.  Consider also, if  you have a submenu, how
  308.     users are to get out of it.
  309.  
  310.     Each  menu or  section of PUI  is controlled  by a file  whose extension is
  311.     "PUI".   The PUI is installed  by putting a  "main" PUI file whose  name is
  312.     specified in CONFIG.  The default is "MAIN.PUI".  Each sub-board in RBBS-PC
  313.     can have a different PUI system if desired.  A PUI file consists of exactly
  314.     10 lines, and the format is:
  315.  
  316.        LINE   CONTENTS
  317.          1    name of novice menu
  318.          2    prompt to display
  319.          3    valid commands, corresponding RBBS-PC commands
  320.          4    which valid commands are menus
  321.          5    names of PUIs that are menus
  322.          6    letter of quit command
  323.          7    prompt for quit command
  324.          8    valid sub-commands of quit command
  325.  
  326.  
  327.  
  328.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                     7-6
  329.  
  330.  
  331.          9    which quit commands are PUIs
  332.          10   names of menu PUIs in quit command
  333.  
  334.     The text in the lines should NOT be enclosed in quotes, except possibly the
  335.     two parts of line 3.
  336.  
  337.     The  novice menu is just  a text file  displayed to novices,  just like the
  338.     default menus (MENU1, MENU2, etc.).   The name can include a  drive or path
  339.     as well as an extension.  The menu PUIs in lines 5 and 10 must be stored in
  340.     the same drive/path as that in line 1.
  341.  
  342.     The prompt  to display is  what all  callers see when  asked for  a choice,
  343.     including experts.  Normally this includes a brief listing of the  commands
  344.     available  along with  a  request  for  a  command.   This  prompt  is  NOT
  345.     dynamically  adjusted to reflect the  security level of  the caller, unlike
  346.     the default prompt  in RBBS-PC,  which removes commands  the caller  cannot
  347.     execute.
  348.  
  349.     Each PUI  defines a "section" of RBBS-PC (just like RBBS-PC has main, file,
  350.     library, and utility sections).  The valid commands are the symbols for the
  351.     acceptable commands  in this PUI  section.  They  must be upper  case only.
  352.     The first part  is the  names of the  commands that  the caller must  give.
  353.     Each  symbol must  be  mapped to  a corresponding  internal symbol  name in
  354.     RBBS-PC which is  set in CONFIG.  This way the  same letter in a given menu
  355.     can be used for different commands in RBBS-PC, just as "S" stands for S)can
  356.     messages in the main  section and S)ubstring search  in the files  section.
  357.     Since  the default  underlying  RBBS-PC commands  use  the same  letter  in
  358.     different  menus,  you  should  first reconfigure  RBBS-PC  to  assign each
  359.     RBBS-PC command  a different underlying symbol.   Then in the  PUI file map
  360.     the letter you  want the caller to use to that  underlying symbol.  Be sure
  361.     in configuration NOT to limit  commands to the current section --  you must
  362.     let RBBS-PC search  in other sections for underlying commands  when it does
  363.     not find it in the current section.
  364.  
  365.     In addition  to the  normal commands available  in RBBS-PC,  the SysOp  can
  366.     include new  commands which invoke other  menus.  These must  be symbols in
  367.     the list of valid commands.
  368.  
  369.     If a valid menu choice is picked, there must be a PUI file for that choice.
  370.     Line 5 tells what prefix the PUI file  has.  Each PUI name must consist  of
  371.     exactly 7 characters.  The  PUI name can be shorter than 7  letters, but in
  372.     the list you must blank fill out to 7 positions to the right.  The first  7
  373.     characters are  for the first valid  menu command, the second  7 characters
  374.     are for the  second valid menu  command, etc.   RBBS-PC will  automatically
  375.     append the extension "PUI" to this file name.  Note that all PUI files must
  376.     be in the same drive/path as the novice menu in line 1.
  377.  
  378.     The last 5  lines in the PUI file concern how  control goes from one PUI to
  379.     another.   The PUI processing  supports a  "quit to" command  in which  the
  380.     caller can jump to other menus - which one is  specified in the subcommands
  381.     to the quit command (just like RBBS-PC's "quit" to command).
  382.  
  383.     Line 6 is the symbol (in the valid commands) which is the  quit-to command.
  384.     It must be a single capital letter.
  385.  
  386.     Line  7 is the prompt  for the quit-to command, to  be presented to callers
  387.     after they select the quit-to command (type ahead is supported).
  388.  
  389.  
  390.  
  391.     PLANNING YOUR USER INTERFACE                                            7-7
  392.  
  393.  
  394.     Line 8 is the list of the valid sub-commands  of the quit-to command.  Each
  395.     command must be a capital letter.
  396.  
  397.     Line 9  tells  which of  the valid  subcommands  are PUI  commands.   If  a
  398.     sub-command  is valid  but not  a PUI  command, control  will be  passed to
  399.     RBBS-PC to process the quit-to  command.  For example, Quit-to S)ystem  for
  400.     hanging up would have to be processed this way.
  401.  
  402.     Line 10 tells  what are the names of the PUI  files for each PUI command in
  403.     line 9.  The format of the PUI names is exactly  the same as in line 5 -- 7
  404.     characters blank filled to the right if shorter.
  405.  
  406.     The following file MAIN.PUI installs the example that was discussed in  the
  407.     previous section:
  408.  
  409.          MMENU
  410.          Enter choice: <F,M,U,G>
  411.          FGMU," G  "
  412.          FMU
  413.          FMENU   MAILM   UMENU
  414.          <5 blank lines follow>
  415.  
  416.     The name of the menu to be displayed initially is MMENU.  The  prompt users
  417.     will see is  "Enter choice: <F,M,U,G>?" (RBBS-PC adds  the trailing "?" for
  418.     prompts).   The four  valid commands are  F, G, M,  and U.   Three of these
  419.     commands invoke  other menus (F,  M, and U), and  G is a  non-menu command,
  420.     i.e. one of  the base  RBBS-PC functions.   The PUI  file name  for "F"  is
  421.     FMENU.PUI,  MAILM.PUI for "M",  and UMENU.PUI for  "U".  Each  of these PUI
  422.     files  gives the same  type of information  as the main PUI.   For example,
  423.     MAILM.PUI might contain
  424.  
  425.          MAILM.MNU
  426.          Enter choice: <E,J,P,Q,R,S,T>
  427.          EJPQRST,EJPQRST
  428.          Q
  429.          MAIN
  430.          <5 blank lines follow>
  431.  
  432.     The novice menu for the mail section is in file MAILM.MNU.  This file might
  433.     contain the following text:
  434.  
  435.          M A I L   S U B S Y S T E M
  436.          ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  437.               E)nter a message
  438.               J)oin a new message base
  439.               P)ersonal mail (review)
  440.               Q)uit to main section
  441.               R)ead messages
  442.               S)can msg headers
  443.               T)opic msg scan
  444.  
  445.     The  prompt will appear immediately  below this line  unless an extra blank
  446.     line is included in the menu file.   There is only one menu command:  Q for
  447.     getting back to the main menu.
  448.  
  449.     The PUI system  can also be  used to emulate  the default RBBS-PC  commands
  450.     with 4 sections.   Four sample files are provided  for accomplishing this:
  451.     XMAIN.PUI, XFILE.PUI,  XUTIL.PUI, and  XLIBR.PUI.   For novice  menus, each
  452.     uses the  standard default  menu that  comes with  RBBS-PC.  These  require
  453.  
  454.  
  455.  
  456.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                     7-8
  457.  
  458.  
  459.     RBBS-PC  to be  configured with  the following  symbols for  the underlying
  460.     RBBS-PC commands:
  461.  
  462.          MAIN =   normal: ABCDEFIJKOPRSTUVW
  463.             reconfigured: ABC>EFIJKOPRSTU\W
  464.  
  465.          FILES =  normal: DGLNPSUV
  466.             reconfigured: DGLNYZ^V
  467.  
  468.          UTIL =   normal: BCEFGLMPRSTU
  469.             reconfigured: !#E$<&M*()-+
  470.  
  471.          GLOBAL = normal: H?QX
  472.             reconfigured: H?QX
  473.  
  474.          SysOp =  normal: 1234567
  475.             reconfigured: 1234567
  476.  
  477.          LIBRARY =normal: ACDGLSV
  478.             reconfigured: []{G}:'
  479.  
  480.     7.7 RBBS-PC's Support of Sub-menus
  481.     ----------------------------------
  482.     Sub-menu support means that an item on  a menu can itself be another  menu,
  483.     so that selecting it results  in a new menu being displayed from  which the
  484.     caller can select yet another option.
  485.  
  486.     The  areas in RBBS-PC  that can have  sub-menu support  include:  answering
  487.     surveys,  bulletins, doors,  joining a conference,  and the  file subsystem
  488.     command to list directories.
  489.  
  490.     A primary  use of sub-menus is  to simplify the user  interface, chiefly by
  491.     allowing  sub-categorization of the option.   For example,  suppose a SysOp
  492.     has  a complex system of doors, including multi-user games (TREK, NAPOLEON,
  493.     3DCHESS), single-user games (D&D,  R&R, PICKUP), and demonstrations (DBIII,
  494.     ORACLE, ADVENT).  These could be presented on a single menu, such as:
  495.  
  496.          The following Doors are available:
  497.  
  498.          Multi-User Games
  499.               TREK - explore the galaxy, compete with 12 other players
  500.               NAPOLEON - be Russia, Italy, or England and fight the computer
  501.               3DCHESS - are you ready, Spock?
  502.  
  503.          Single-User Games
  504.               D&D - the Unix dungeons and dragons!
  505.               R&R - welcome to Taipei, Tokyo, or Bangkok, soldier!
  506.               PICKUP - do you have what it takes?
  507.  
  508.          Demos - all self running
  509.               DBIII - Special version of DB3 adopted for remote usage
  510.               ORACLE - see the power of SQL.  Full screen if you emulate ANSI.
  511.               ADVENT - our own home brewed ...
  512.  
  513.     With sub-menus, the user could see a single, 3 item menu
  514.  
  515.          Doors are available for:
  516.          MGAME - multi-user games
  517.          SGAME - single-user games
  518.  
  519.  
  520.  
  521.     PLANNING YOUR USER INTERFACE                                            7-9
  522.  
  523.  
  524.          DEMO - self running demos
  525.  
  526.     When the caller  picks one of these three,  a new menu comes up  that lists
  527.     the  particular doors for each category.   For example, after picking MGAME
  528.     the caller sees
  529.  
  530.          Multi-User Games available include:
  531.  
  532.          TREK      - explore the galaxy, compete with 12 other players
  533.          NAPOLEON  - be Russia, Italy, or England and fight the computer
  534.          3DCHESS   - are you ready, Spock?
  535.  
  536.     RBBS-PC's sub-menu  capabilities allow SysOps to  set up "tree-structured",
  537.     "key word" paths to options.  Bulletins provide an example  where this type
  538.     of structure  can be very useful.   Bulletins have  two main uses:   short,
  539.     system-wide  announcements, and a standard stock of text files for policies
  540.     and  procedures for a RBBS-PC.  Some SysOps, however, have wanted to put up
  541.     an elaborate system of announcements, where in fact these "bulletins" are a
  542.     featured  way of presenting data  to callers.   For example, an association
  543.     published 300 short pamphlets under a  dozen categories, and wants to  make
  544.     this information available  on-line.   Sub-menus fit this  need very  well.
  545.     The main bulletin menu could read:
  546.  
  547.          Bulletins are available for:
  548.  
  549.               NURSES - nurses
  550.               OB - obstetricians
  551.               PED - pediatricians
  552.               FAM - family physicians
  553.  
  554.          Please type in the category you want:
  555.  
  556.     OB, instead of being a bulletin, is a sub-menu that displays:
  557.  
  558.          The  following bulletins are available for OBSTETRICIANS.   Each entry
  559.          shows the length and price per glossy copy.
  560.  
  561.               NAT - natural childbirth, 8 pages, $3
  562.               MIDW - midwives. 20 p., $5
  563.               NUTRI - special nutritional needs of pregnant women, 25p, $6
  564.               FPLAN - family planning services, 40 p, $3
  565.               DRUG - drugs to beware when pregnant, 50 p., $5
  566.  
  567.     When the caller picks MIDW, the associated document is displayed.   In this
  568.     example,  bulletins become  a  menu-driven way  of  selecting documents  to
  569.     browse.
  570.  
  571.     In  order  for the  previous example  to  work,   RBBS-PC  utilizes "named"
  572.     bulletins.   For example, selecting "B"  as the bulletin prefix,  the above
  573.     bulletins would be files BNAT,  BMIDW, BNUTRI, BFLAN, and BDRUG.   However,
  574.     RBBS-PC's  "new  bulletin  search"  function  will  only  search for  named
  575.     bulletins if  they are listed  in the file x.FCK  (where x is  the bulletin
  576.     prefix).   Also, named bulletins are not  listed in the "new" bulletin list
  577.     as numbered bulletins are.
  578.  
  579.     7.7.1 How to Implement Sub-menus
  580.     --------------------------------
  581.     If "XXX" is an option on a menu, simply create a file named  "XXX.MNU" that
  582.     has in it the  text for the menu.  Put this file  in the same drive/path as
  583.  
  584.  
  585.  
  586.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-10
  587.  
  588.  
  589.     the non-menu  options (e.g. where the  "BAT" files go for  doors, where the
  590.     bulletin files to  display are put,  where the directory  files are).   For
  591.     example,  if  "B"  is  the bulletin  prefix,  the  above  example would  be
  592.     implemented by  adding the  files "BNURSE.MNU", "BOB.MNU",  "BPED.MNU", and
  593.     "BFAM.MNU".    Put  these  files  on the  same  drive  that  the  bulletins
  594.     themselves go.
  595.  
  596.     The .MNU extension  alerts RBBS-PC  to the fact  that the file  is a  menu.
  597.     Thus, RBBS-PC  will only LIST  the menu file,  rather than ACT  on it (e.g.
  598.     3DCHESS.BAT is a door to be run, while 3DCHESS.MNU is a menu to be listed).
  599.  
  600.     7.7.2 Shared Options Across Sub-menus
  601.     -------------------------------------
  602.     RBBS-PC supports identical choices from different sub-menus.  E.g. the main
  603.     menu  has sub-menus  A and  B, and  BOTH of  these sub-menus could  have an
  604.     option X on them, which  triggered a different action (based on  which sub-
  605.     menu it X  was selected from).  The way that this works is RBBS-PC searches
  606.     both for the global prefix and the user response as well as looking for the
  607.     current  prefix and user response.  If the  bulletin prefix is "B", and the
  608.     structure of bulletins is as follows:
  609.  
  610.               /   1        BM is main bulletin menu, B is the prefix
  611.            A ---- 2        BMA.MNU  submenu get with choice A
  612.          /    \   3        BMB.MNU  submenu get with choice B
  613.         /                  BMC.MNU  submenu get with choice C
  614.        /      /   1
  615.     BM --- B ---- 2        BMA1, BMA2, BMA3 bulletins active at BA
  616.        \      \   3        BMB1, BMB2, BMB3 bulletins active at BB
  617.         \                  BMC1, BMC2, BMC3 bulletins active at BC
  618.          \    /   1
  619.            C ---- 2
  620.               \   3
  621.  
  622.     7.8 RBBS-PC's "Macro" Command Support
  623.     -------------------------------------
  624.     RBBS-PC's  "macro"  support  expands   a  single  keystroke  into  multiple
  625.     keystrokes.  It allows RBBS-PC to be tailored in even  a greater variety of
  626.     ways  than before  because  a single  command can  be  set up  to invoke  a
  627.     sequence of  multiple  RBBS-PC commands.   The  concept is  similar to  the
  628.     keyboard  macro function found in  many terminal emulators,  except that in
  629.     RBBS-PC   the  SysOp  defines  the  macros  and  the  caller  invokes  them
  630.     transparently without knowing.
  631.  
  632.     Macros add a  new dimension to RBBS-PC  commands -- commands can  be a full
  633.     word rather than just a single letter.   A macro is invoked by a name up to
  634.     8 characters.   For example, "DOOR" and "OPEN" can be used to invoke doors.
  635.     This makes it easy to make all commands  available on a single level, since
  636.     D  could trigger  a download,  while the  word DOOR  will trigger  the door
  637.     function.
  638.  
  639.     Macros can  be used to abbreviate a longer series of commands. If the SysOp
  640.     wants to use "A)bandon conference", all that need be done is to add a macro
  641.     called "A" whose  content is "J M"  (join main).  Or  if N)etmail is to  be
  642.     used to read Fido-net compatible message bases, a macro called "N" could be
  643.     set  up as "D  NETMAIL" (use door  called NETMAIL).  RBBS-PC  thus can have
  644.     UNLIMITED commands.
  645.  
  646.     A string  of RBBS-PC commands can be  stored in a macro  for many different
  647.     types of purposes, including (but not limited to):
  648.  
  649.  
  650.  
  651.     PLANNING YOUR USER INTERFACE                                           7-11
  652.  
  653.  
  654.          setting up demos,
  655.          showing a user what to do rather than just explaining it in words,
  656.          automated testing of RBBS-PC features
  657.  
  658.     Macros can  also be  used to make  the same type  of function  do different
  659.     work.  For example, the  B)ulletin command basically displays a text  file.
  660.     Suppose an association  wants to  let persons order  pamphlets and  preview
  661.     them  on-line.   Rather  than bury  the  ordering function  insider A)nswer
  662.     questionnaire  and the  preview  function inside  B)ulletins, the  commands
  663.     PREVIEW and  ORDER  can be  added  as macros,  where  ORDER stands  for  "A
  664.     ORDWHAT"  AND  "ORDWHAT" is  a submenu  listing what  can be  ordered. Each
  665.     option on the submenu is a questionnaire.  PREVIEW similarly is "B PREWHAT"
  666.     where  "PREWHAT"  is a  submenu listing  the  available pamphlets  that are
  667.     stored as text files.
  668.  
  669.     Macros can be built to  provide interactive help to callers.   For example,
  670.     you can put  up a macro called EZDOWN to help people download.  It explains
  671.     everything, asks for the file name  and protocol, and tells the caller what
  672.     they should be doing on their end, and then drives the download.
  673.  
  674.     Macros   can  be   used  to   provide  integrated   data  bases.     Unlike
  675.     questionnaires, you can totally control how data is written to a file.  You
  676.     can put in  labels, or data only,  put the values  in quotes, separate  the
  677.     values by commas, etc.  This is done by creating a template into which data
  678.     values are written.
  679.  
  680.     Macros  can be used to give  "tours" of your RBBS-PC --  to showcase new or
  681.     special features.
  682.  
  683.     Macros  can  be controlled  via security  level  access, just  like regular
  684.     commands, and they can be forced to operate only in certain contexts.
  685.  
  686.     Macros can be
  687.  
  688.        - invoked anywhere within RBBS-PC -- including questionnaires,
  689.        - unlimited in length,
  690.        - used even when the caller has "turbo" key feature enabled,
  691.        - used with SmartText (see section 7.9),
  692.        - used to store responses that can be manipulated later, and
  693.        - used to support graphics versions of text.
  694.  
  695.     It is important to remember that a macro will be ignored if its name is the
  696.     same as any command.   To replace a command  with a macro, you must  insure
  697.     that the letter  for the command  has been  reassigned.  CONFIG  parameters
  698.     30-34 allow such reassignments to be easily accomplished.
  699.  
  700.     Some contexts  will not accept macros,  such as when RBBS-PC  prompts for a
  701.     search string.
  702.  
  703.     Macro  commands with more than one letter  override all others.  This means
  704.     that  the macro interpretation will prevail if more than one interpretation
  705.     is possible.   For example,  in the  absence of macros  the command  "door"
  706.     would  the interpreted  as the command  "d", so  that saying  "door" in the
  707.     files  section would  be  download.   But a  "DOOR.MCR"  would be  executed
  708.     instead when it  exists.  One  letter commands,  however, will be  executed
  709.     when  they match a command  letter, and so any macros  will be ignored that
  710.     have the same one letter name the same as a command.
  711.  
  712.  
  713.  
  714.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-12
  715.  
  716.  
  717.     7.8.1 How to Set Up "Macros"
  718.     ----------------------------
  719.     To  use macros,  two CONFIG parameters  must be specified:   the drive/path
  720.     where macro files are  stored (CONFIG parameter 79)  and the extension  the
  721.     macro files will  have (CONFIG parameter  80).  The  defaults are "C:"  and
  722.     "MCR".  To  create a macro named X, simply create  a file with prefix X and
  723.     the macro  extension and place in it the macro  drive/path.  If you are not
  724.     using any macros, RBBS-PC will run faster if you specify NO macro extension
  725.     in CONFIG parameter 80.
  726.  
  727.     The  first line  within a  "macro" controls  access to  the macro,  both by
  728.     security level, and a  limitation on the  scope of the  macro, in which  it
  729.     will be operative, including
  730.  
  731.        - anywhere inside a section
  732.        - anywhere inside a command
  733.        - only at a section and not inside.
  734.  
  735.     The format of the first line is:
  736.  
  737.               <SecLevel>/<constraint>
  738.  
  739.     where <SecLevel>  is the minimum  security required to  run the  macro, and
  740.     <constraint> is the  section (M for main, F  for file, U for utility,  or @
  741.     for library)  and command  letter the  macro is confined  to (use  original
  742.     command letter, not the reassigned ones).  For example
  743.  
  744.               4/M
  745.  
  746.     means  that security level  4 is  required, and the  macro runs  only at or
  747.     inside the main section prompt.
  748.  
  749.               5/MB
  750.  
  751.     means  that security  level 5  is required and  the macro  runs only  at or
  752.     inside the main section bulletin command.  Thus the macro file 1.mcr
  753.  
  754.               2/MJ
  755.               {EN
  756.               RBBS
  757.  
  758.     means that when inside the main  J)oin, the text "RBBS" will be substituted
  759.     for "1".   (So "J 1" does  the work of "J  RBBS".)  The "{EN"  means not to
  760.     echo what the macro substitutes (user does not see "RBBS").
  761.  
  762.     To make a macro  operative only at a section prompt and not inside, add a "
  763.     /" to the end of the section constraint.  For example,
  764.  
  765.               4/M /
  766.  
  767.     means that the macro applies only at the main section prompt.  For example,
  768.     the macro SP.MCR
  769.  
  770.               4/M /
  771.               {EN
  772.               J SEMIPRV
  773.  
  774.     will  substitute "J SEMIPRV" for "SP" when at  the main prompt, but NOT for
  775.     "SP" inside the message read command ("R SP L").
  776.  
  777.  
  778.  
  779.     PLANNING YOUR USER INTERFACE                                           7-13
  780.  
  781.  
  782.     Note:  a macro will be ignored if its name is the same as a command symbol.
  783.     To use  1, 2, 3, etc.  for macro commands,  you must disable  or substitute
  784.     other symbols for the SysOp commands.
  785.  
  786.     The first line  of a macro  must be the minimum  security level to  use the
  787.     macro.   The macro will  simply be ignored  if the caller  has insufficient
  788.     security.  The second line  will be parsed and replace the macro name.  The
  789.     remaining lines will be read from disk and processed as required.
  790.  
  791.     Macro commands have the same structure as SmartText variables:
  792.  
  793.          <command prefix><command name>
  794.  
  795.     where <command prefix> is the  SmartText command specified in CONFIG.   The
  796.     symbol "{" (ASCII 123)  is the default.  The <command name> consists of two
  797.     characters.  Lines that are  not valid macro commands are simply  passed to
  798.     RBBS-PC  as if the  user had  typed them in.   There  are three differences
  799.     between SmartText variables and macro commands:
  800.  
  801.     (1)  Macro commands must be the first  three characters on a line,  whereas
  802.          SmartText variables can occur anywhere on a line.
  803.  
  804.     (2)  Macro commands can have an argument after the command name, and(
  805.  
  806.     (3)  A macro command can apply to a block of lines following it.
  807.  
  808.     7.8.2 Macro Commands
  809.     --------------------
  810.     RBBS-PC "Macro" Commands include the capability of having commands executed
  811.     within  the "macro" rather than  simply passing keystrokes  to RBBS-PC.  In
  812.     all prompts and blocks,  substitution is supported for both  stored answers
  813.     SmartText  variables.  The following  is a  list  and description  of valid
  814.     "macro" commands:
  815.  
  816.     *0 - display what follows on the line with no carriage return.
  817.     *1 - display what follows on the line with a carriage return.
  818.     *B - display what follows on subsequent lines.
  819.     *F - display the named file that follows.
  820.     nn - display a prompt and store result in work variable nn.
  821.     WT - pause for the number of seconds specified after "WT".
  822.     >> - append the following block of text to the file specified.
  823.     ST - Stack the characters immediately following the "ST".
  824.     M! - Execute the named macro that follows on the same line.
  825.     ON - Case logic for branching within macros based on stored results.
  826.     EY - Echo the text passed in macros as keystrokes.
  827.     EN - Do not echo the macro keystrokes.
  828.     << - Display fields from a file in a form.
  829.     := - Assign value to a work variable
  830.     LV - Verify that answer of one in a list
  831.     NV - Verify that answer is between two integers
  832.     CV - Verify that answer is between two character values
  833.     LO - Set location for Fast File Searches for download, upload, view
  834.  
  835.     The syntax and an example of each command follows:
  836.  
  837.     *0 - display what follows on the line with no carriage return.
  838.  
  839.               {*0Press any key to continue
  840.  
  841.  
  842.  
  843.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-14
  844.  
  845.  
  846.     *1 - display what follows on the line with a carriage return.
  847.  
  848.               {*1{FN, I hope you enjoyed your tour of the board!
  849.  
  850.          The  caller's  first name  is substituted  for the  SmartText variable
  851.          "{FN."
  852.  
  853.     *B - display  what follows on subsequent  lines, each line  with a carriage
  854.          return, up to the line beginning with "{END".
  855.  
  856.               {*B
  857.               This is  an example  of a  macro's  ability to  display
  858.               multiple lines.  The macro command is
  859.               {*B
  860.               and  it will display all lines  until it encounters one
  861.               beginning with {END.  Like it, {FN?
  862.               {END
  863.  
  864.          The caller will seen everything between the first and last lines, with
  865.          the first name substituted into the last line displayed.
  866.  
  867.     *F - display the named file that follows.
  868.  
  869.               {*F L:\RBBS\HELP.LST
  870.  
  871.          will display the file HELP.LST.
  872.  
  873.     nn - use the text that follows on the line as a prompt and store the answer
  874.          in an  internal working variable numbered  nn.  nn must  be two digits
  875.          and  can be 01,  02, 03,  ..., 99.   CONFIG parameter  94 controls the
  876.          maximum # of work variables.
  877.  
  878.               {01Please enter the Department you work for:
  879.               {02Please enter your Office number:
  880.  
  881.          This will store the answers in  work variable # 1 and 2, which  can be
  882.          subsequently referenced as "[1]" and "[2]".  You can have as many work
  883.          variables as specified  in CONFIG  parameter 94.   Variables that  are
  884.          reused have their values overwritten.
  885.  
  886.     WT - pause for the number of seconds specified after "WT".
  887.  
  888.               {WT 2
  889.  
  890.          will wait for 2 seconds.
  891.  
  892.     >> - append the following block of text to the file specified on this line.
  893.  
  894.               {>> C:MACRO.DAT
  895.               "{FN","{LN","[1]","[2]"
  896.               {END
  897.  
  898.          will append the  following line to the  file named MACRO.DAT  on drive
  899.          C:, assuming the caller is KEN  GOOSENS, and he responded to the above
  900.          prompts for  Department  with "Controller"  and Office  # with  "107".
  901.          Then the line what would be written out is:
  902.  
  903.               "KEN","GOOSENS","Controller","107"
  904.  
  905.  
  906.  
  907.     PLANNING YOUR USER INTERFACE                                           7-15
  908.  
  909.  
  910.          As many lines can be included as desired.   Simply end the block to be
  911.          written out with "{END" as the beginning of the line.
  912.  
  913.          Some  data base managers want fixed length  files and this is possible
  914.          in the  macro append.    Just add  "/FL" on  the  macro command  line.
  915.          Rather than replace,  the substitution  will overlay the  line at  the
  916.          "[",  thus keeping  the output fixed  length.   Lets suppose  that the
  917.          first  work variable has "A" as a  value, the second work variable has
  918.          the value "123456",  the third work variable  has "Henry" as  a value,
  919.          and the caller's first name is KEN.  Then
  920.  
  921.               {>> C:\RBBS\DAT.FIL /FL
  922.               [1][2]....[3]...............{FN........
  923.               {END
  924.  
  925.          would add the following line into DAT.FIL
  926.  
  927.               A  123456.Henry.............KEN.........
  928.  
  929.          Normally, blanks would be put where dots are show.
  930.  
  931.     ST - Stack the characters immediately following the "ST".
  932.  
  933.               {ST
  934.  
  935.          will stack a carriage return (no characters).  And
  936.  
  937.               {STD [1] [2]
  938.  
  939.          would  stack "D  RBBS-EXE.ARC Z"  - as  if they  were typed  and ENTER
  940.          pressed - if  the first work variable had "RBBS-PC.EXE" and the second
  941.          work variable held "Z".  It is important to note that  "macros" are so
  942.          transparent to  RBBS-PC that if you  use macros to display  text at an
  943.          RBBS-PC  prompt like "Enter command?  ", RBBS-PC will  continue to sit
  944.          there waiting for  an answer.   A stacked carriage  return at the  end
  945.          will cause  the prompt  to be  redisplayed, though the  effect of  the
  946.          stack will vary with the particular prompt.
  947.  
  948.     M! - Execute the named macro that follows on the same line.  E.g.
  949.  
  950.               {M! ORDER
  951.  
  952.          will execute the macro called  ORDER.  RBBS-PC does NOT return  to the
  953.          invoking macro when the named macro is complete.  Also,  The full file
  954.          name of the  macro to execute is not here  used (i.e. ORDER.MCR), only
  955.          the file prefix -- ORDER.
  956.  
  957.          As  is shown in the example of the ON command, the macro name can have
  958.          a drive/path  and/or extension.  If  only a prefix is  put in, RBBS-PC
  959.          will  automatically  add  the  drive/path  and  extension  for  macros
  960.          specified in  CONFIG parameter  79  and parameter  80.   Putting in  a
  961.          drive/path/extension that  is different from CONFIG's  assures that no
  962.          caller can invoke the macro -- it only can be used internally  by your
  963.          application.
  964.  
  965.     ON - Case logic for macros.  This allows responses to be tested against and
  966.          branching logic developed within a "macro".  An example would be:
  967.  
  968.               {ON 1
  969.  
  970.  
  971.  
  972.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-16
  973.  
  974.  
  975.               {==A
  976.               {M! D:\HIDDEN\CHOICEA.MCR
  977.               {==B
  978.               {*1You have selected option B
  979.               {02Why did you select B?
  980.               {==C
  981.               {M! D:\HIDDEN\CHOICEA.MCR
  982.               {END ON
  983.  
  984.     EY - Echo  the text passed in  macros as if keystrokes.   The default is to
  985.          echo.
  986.  
  987.     EN - Do not echo the macro keystrokes.  An example would be:
  988.  
  989.               {EN
  990.               {*1 The following commands will be executed but now shown
  991.               {01 Press Enter when ready
  992.               R L
  993.               A
  994.               {EY
  995.               {*1 now you will see the responses to the prompts
  996.               {01 Press Enter when ready
  997.               R L
  998.               A
  999.  
  1000.     << - Display fields  from a  file  in a  form.   This is  one  of the  most
  1001.          powerful macro commands.  It allows data to be stored in compact, data
  1002.          format but retrieved into a  form for display to a caller.   There are
  1003.          5 parameters that can follow the macro command:
  1004.  
  1005.          <file name> <file format> <data#> <submode> <rec-pause>
  1006.  
  1007.           where:
  1008.  
  1009.          "<file name>" is the name of the data file that has records to read,
  1010.  
  1011.          "<file format>" is "/V"  if data is stored  in variable length  format
  1012.          and "/F" if fixed length format,
  1013.  
  1014.          "<data#>" is the  number of separate  fields in a record  for variable
  1015.          length data and the length of the data if fixed length,
  1016.  
  1017.          "<submode>" is the mode used to  substitute data in the following form
  1018.          "/FL" if the form is fixed length, meaning that data  is overlaid into
  1019.          the form so as not to change any lengths.
  1020.  
  1021.          "<rec-pause>" should  be "/1" if you  want to pause  after each record
  1022.          rather than when the screen fills.
  1023.  
  1024.          An example of a "macro" that uses this capability is as follows:
  1025.  
  1026.     {*1 -TOPIC-    - DATA # -       - VOICE # -    -First Name-    -Last Name-
  1027.     {<< C:\RBBS\RHLP.DAT /V 5 /FL
  1028.     [1]         [2]              [3]             [5]             [4]
  1029.     {END
  1030.  
  1031.     Note that spaces occur after the "[4]".  If the file RHLP.DAT contains
  1032.  
  1033.     "DOORS","703-978-6360","0","Ken","Goosens"
  1034.  
  1035.  
  1036.  
  1037.     PLANNING YOUR USER INTERFACE                                           7-17
  1038.  
  1039.  
  1040.     "PROTOCOLS","407-627-6969","407-627-9767","Doug","Azzarito"
  1041.  
  1042.     then the caller would see
  1043.  
  1044.      -TOPIC-    - DATA # -       - VOICE # -    -First Name-    -Last Name-
  1045.     DOORS       703-978-6360     0               Ken             Goosens
  1046.     PROTOCOLS   407-627-6969     407-627-9767    Doug            Azzarito
  1047.  
  1048.     The same example using fixed length data would be
  1049.  
  1050.     {*1 -TOPIC-    - DATA # -       - VOICE # -    - Name -
  1051.     {<< C:\RBBS\RFLH.DAT /F 69 /FL
  1052.     [1](34:12)    [1](46:12)       [1](58:12)      [1](1:33)
  1053.     {END
  1054.  
  1055.     where RFLH.DAT contains:
  1056.  
  1057.     Ken Goosens                      DOORS       703-978-63600
  1058.     Doug Azzarito                    PROTOCOLS   407-627-6969407-627-9767
  1059.  
  1060.     This would produce the following for the caller:
  1061.  
  1062.      -TOPIC-    - DATA # -       - VOICE # -    - Name -
  1063.     DOORS       703-978-6360     0               Ken Goosens
  1064.     PROTOCOLS   407-627-6969     407-627-9767    Doug Azzarito
  1065.  
  1066.     Note that work fields support sub-field references in the format:
  1067.  
  1068.               [n](x:y)
  1069.  
  1070.     where n is the work field number,  "x" is the beginning column, and "y"  is
  1071.     the # of  bytes to  get.  If  work field  two had a  value "123abcde"  then
  1072.     "[2](3:4)" would have "3abc" as its value.  Fixed length records are always
  1073.     referenced as work variable one.
  1074.  
  1075.     := - Assign a  value to a work variable.   Work variables can be assigned a
  1076.          value inside a macro.  The command to do this is ":=".  E.g.
  1077.  
  1078.               {:= 5 OK
  1079.  
  1080.          assigns string "OK" to work variable 5.
  1081.  
  1082.     LV,  NV, and CV  - Macros can edit  the responses to  questions.  Edits can
  1083.     constrain the answer to
  1084.  
  1085.          - one of a list
  1086.          - a numeric value between two values
  1087.          - a character value between two values
  1088.  
  1089.          An editing  constraint  must be  put  in  front of  the  actual  macro
  1090.          question  it applies  to, and a  constraint applies  only to  the next
  1091.          question and does not remain operative.
  1092.  
  1093.          The  commands for  these  are respectively  "LV"  (List Verify),  "NV"
  1094.          (Numeric Verify), and "CV"  (Character Verify).  The list  verify uses
  1095.          the first character  after the  command as a  delimiter between  valid
  1096.          responses.  E.g.  "{LV;R;A;E;" means that only "R",  "A", and "E" will
  1097.          be  accepted as  answers ("{LV/R/A/E/"  would have  the same  effect).
  1098.  
  1099.  
  1100.  
  1101.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-18
  1102.  
  1103.  
  1104.          Semi-colon  is  the best  delimiter in  general  because it  cannot be
  1105.          entered as a value.
  1106.  
  1107.          Numeric and Character verify  check inclusive ranges.  Thus "{NV 7 11"
  1108.          will accept 7, 8, 9, 10, or 11.   The numeric value must be an integer
  1109.          between -32,768 and 32,767.  To  accept answers B through E, the macro
  1110.          edit command is "{CV B E".
  1111.  
  1112.          Whenever an answer fails  an edit, the message "Invalid  answer <...>"
  1113.          is given with the  answer received between brackets, and  the question
  1114.          is asked again.  An example of a macro with edits is:
  1115.  
  1116.               4
  1117.               {*1 Verification macro
  1118.               {*1 now checking list...
  1119.               {LV;A;F;W;
  1120.               {01 Enter A, F, or W
  1121.               {*1 now testing numeric range...
  1122.               {NV 5 15
  1123.               {01 Enter a number between 5 and 15
  1124.               {*1 now testing character range...
  1125.               {CV D J
  1126.               {01 Enter a character between D and J
  1127.  
  1128.     LO - Sets  location  that a  file  is  to be  searched  for  in an  upload,
  1129.          download, or view  request.   Followed  by a drive path.   Useful when
  1130.          want  to have a macro execute  in front of a download  or upload for a
  1131.          file  which is really  available (see section 12.9).   Applies only to
  1132.          Fast File Search.  For example,
  1133.  
  1134.               {LO  F:\DF1\
  1135.  
  1136.          would set the file location to drive F subdirectory DF1.
  1137.  
  1138.     7.8.3 A Sample Macro
  1139.     --------------------
  1140.     Suppose A)bandon conference is to  be implemented in RBBS-PC.  To  do this,
  1141.     the  command A)nswer  questionnaires must be  assigned a  different letter.
  1142.     Else A will always invoke answer instead.  Then the macro file could
  1143.     contain
  1144.               5
  1145.               J M
  1146.  
  1147.     The command "A" will  then be followed by "Rejoining MAIN".   Incidentally,
  1148.     if the macro had been implemented by
  1149.  
  1150.               5
  1151.               J
  1152.               M
  1153.  
  1154.     The only  difference is that the prompt for what conference to join will be
  1155.     displayed, "M" then would  be displayed as if the caller  had typed it, and
  1156.     then main would be rejoined.  The difference is caused by the fact that the
  1157.     first line after the  security level is what replaces the macro name, so in
  1158.     the first case "M" preempts the prompt but not in the second.
  1159.  
  1160.  
  1161.  
  1162.     PLANNING YOUR USER INTERFACE                                           7-19
  1163.  
  1164.  
  1165.     7.8.4 On-line Data Base With Macros & Questionnaires
  1166.     ----------------------------------------------------
  1167.     RBBS-PC provides the  SysOp with the ability to offer  callers access to an
  1168.     on-line  database both  internally  (using macros  and questionnaires)  and
  1169.     externally to RBBS-PC (see Appendix R).
  1170.  
  1171.     RBBS-PC's internal Remote Data Base feature gives the SysOp the ability to:
  1172.  
  1173.        - set up unlimited numbers of named data bases
  1174.        - set up menus to interact with the user
  1175.        - prompt users for data
  1176.        - use Metavariables - both work variables and SmartText variables.
  1177.        - store user's  answers  in work  variables.   Any  subfield  in a  work
  1178.          variable can be referenced.
  1179.        - display, or store all metavariables
  1180.        - process commands conditionally
  1181.        - save  Metavariables to  file through  templates, allowing  data  to be
  1182.          stored in virtually any format desired
  1183.        - retrieve data into templates for display.
  1184.        - do full screen data entry
  1185.  
  1186.     RBBS-PC's support  for "full screen"  questionnaires and macros  takes some
  1187.     work on the SysOp's  part.  The SysOp must  use ANSI screen commands.   The
  1188.     SysOp must then arrange to transmit the "template" that clears the  callers
  1189.     screen and  writes the appropriate static text (lines, labels, etc.) on the
  1190.     callers  screen.  Then the data the user  is to see is transmitted onto the
  1191.     caller's screen.   The "full screen"  support does not allow  the caller to
  1192.     use keys like tab  and cursor arrows to move  around on the screen.   It is
  1193.     "full screen" in the sense that the caller sees  all the data that is to be
  1194.     entered and the cursor moves from field to field.
  1195.  
  1196.     On-line Database Example
  1197.     ------------------------
  1198.     This  application manages a  data base of  callers who are  willing to help
  1199.     with RBBS-PC  by topic.  It is controlled at  a high level by the following
  1200.     questionnaire.
  1201.  
  1202.     C:DUMMY.DAT,4
  1203.     * This questionnaire is for finding help with RBBS-PC by topic.
  1204.     * Please register yourself if you
  1205.     *   -  are willing to help others, and
  1206.     *   -  know enough about a topic to help
  1207.     *
  1208.     * Examples of topics people need help with:
  1209.     *   Desqview       Modem models (HST, Everex, USR Internal, etc.)
  1210.     *   PC-Slaves      Protocols     Conferences    FMS
  1211.     *   Doors          DoubleDos     Sub-boards     PUI
  1212.     *   Questionnaires 10-Net        Macros         Uploads
  1213.     *   MU-Purge       File maint.   Personal dnld  Caller Analysis
  1214.     *
  1215.     :-[prompt]-
  1216.     T
  1217.     ? V)iew database, E)nter new data, Q)uit (V,A,Q)
  1218.     =V-[view]-=E-[add]-=Q-[quit]-= -[prompt]-
  1219.     :-[view]-
  1220.     M C:\RBBS\VIEWHELP.MCR
  1221.     >-[prompt]-
  1222.     :-[quit]-
  1223.     @
  1224.  
  1225.  
  1226.  
  1227.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-20
  1228.  
  1229.  
  1230.     :-[add]-
  1231.     *                  703-978-6360
  1232.     ?1 BBS data number
  1233.     *                                   703-978-4339
  1234.     ?2 Voice # (evening, 0 not to give)
  1235.     * You can specify as many topics as desired, one at a time.
  1236.     *
  1237.     :-[topic]-
  1238.     ?3 RBBS-PC topic you will help others with, or Q)uit
  1239.     =Q-[prompt]-= -[addrec]-
  1240.     :-[addrec]-
  1241.     * -Topic-         - Data # -      - Voice # -   Last Name       First Name
  1242.     */FL[3]              [1]             [2]            {LN             {FN
  1243.  
  1244.     T
  1245.     ?Really add this record (Y,N)
  1246.     =Y-[really]-=N-[topic]-= -[addrec]-
  1247.     :-[really]-
  1248.     M C:\RBBS\ADDHELP.MCR
  1249.     >-[topic]-
  1250.  
  1251.     Two macros are used by this questionnaire:
  1252.     VIEWHELP.MCR for displaying the data base, and
  1253.     ADDHELP.MCR for appending new data to the data base.
  1254.  
  1255.     VIEWHELP.MCR contains
  1256.  
  1257.     5
  1258.     {*1 -Topic-          - Data # -       - Voice # -    Last Name        First
  1259.     Name
  1260.     {*F RBBSHELP.DAT
  1261.  
  1262.     ADDHELP.MCR contains
  1263.  
  1264.     5
  1265.     {>> RBBSHELP.DAT /FL
  1266.     [3]              [1]             [2]            {LN             {FN
  1267.     {END
  1268.  
  1269.     Full Screen Example
  1270.  
  1271.     Full screen is available only in a color graphics version of questionnaires
  1272.     and macros.   A long application for collecting BBS information is given in
  1273.     these following files:
  1274.  
  1275.     REGRBBS.DEF  - Questionnaire driver, TTY version
  1276.     REGRBBSC.DEF - Color graphics version of questionnaire driver
  1277.     VUNRBBS.MCR  - View data base macro, TTY version
  1278.     VUNRBBSC.MCR - View data base macro, Color graphics version
  1279.     SVRBBS.MCR   - Macro to save data to a comma separated data file
  1280.  
  1281.     These files can  generally be  download from most  bulletin board  systems.
  1282.     However,  they are definitely available  on Ken Goosens'  RBBS-PC system at
  1283.     (703) 978-6360.
  1284.  
  1285.     Hints for Building Remote Data Base Applications
  1286.     ------------------------------------------------
  1287.     Generally you will have:
  1288.  
  1289.  
  1290.  
  1291.     PLANNING YOUR USER INTERFACE                                           7-21
  1292.  
  1293.  
  1294.        - a  questionnaire  driver  that  gives  caller  option  to  exit,  view
  1295.          database, or Enter new data
  1296.        - a macro to retrieve data from file to a form
  1297.        - a macro to save data in a data base format
  1298.        - a data entry routine in the questionnaire.
  1299.  
  1300.     Creating  a "full-screen" application is more complicated that than a line-
  1301.     at-a-time  (i.e. TTY) application.   For full-screen applications, you will
  1302.     want to:
  1303.  
  1304.        - paint a template with everything but the data values, such  as row and
  1305.          column labels and titles.
  1306.        - clear  out the  existing values  in a  form and  then put  in the  new
  1307.          values.
  1308.  
  1309.     Only the changes to  the screen are transmitted rather  than retransmitting
  1310.     the entire screen when only a part changes.
  1311.  
  1312.     ANSI  commands are used to control the screen.   Where [ESC] stands for the
  1313.     one-character Escape (ASCII 27), the most useful ANSI commands to know are:
  1314.  
  1315.      [ESC][2J    - clear the screen.
  1316.  
  1317.      [ESC][K     - clear from current cursor  position to end of line.   Cursor
  1318.                    position after clearing is same as before.
  1319.  
  1320.      [ESC][X;Yf  - position  the  cursor  on   row  x  and  column  Y.     E.g.
  1321.                    "[ESC][5;10f" positions on column 10 of row 5.
  1322.  
  1323.     Case is  significant in ANSI  commands, so beware  that "[ESC][k" will  NOT
  1324.     clear to end of line, and "[ESC][1;7F" will not position the cursor.
  1325.  
  1326.     You  can use ANSI commands to set color  and blink characters.  An easy way
  1327.     consistent with RBBS-PC is to set colors using the  SmartText variables C0,
  1328.     C1,  ...,  C4, where  1-4  are  the colors  set  in  CONFIG parameter  323,
  1329.     parameter 324, parameter 325, and parameter 326.  C0 is "emphasis off," and
  1330.     restores  normal text  color preference  of the  caller.   An  example that
  1331.     clears the  screen, sets color to 1, positions on line 1, column 15, prints
  1332.     "-Sample  Title-", sets color to caller's text preference, prints 2 spaces,
  1333.     and then prints value of work variable 1 is as follows:
  1334.  
  1335.     [ESC][2J{C1[ESC]1;15f-Sample Title-{C0  [1]
  1336.  
  1337.     7.9 RBBS-PC's "SmartText" Variables
  1338.     -----------------------------------
  1339.     SmartText allows  the  SysOp to  substitute pre-defined  variables in  text
  1340.     files  as menus,  bulletins, help,  welcome files,  as  well as  macros and
  1341.     questionnaires.    This  allows the  SysOp  to  present to  each  caller an
  1342.     interface that is not only "programmable", as discussed in section 7.6, but
  1343.     also tailored to the specific caller.
  1344.  
  1345.     Some applications for SmartText include:  addressing the caller by name, as
  1346.     well  as referring customized variables for the caller, such as city/state.
  1347.     For  example, the  welcome file  could say,  "Hi, <first  name>, how's  the
  1348.     weather in <city/state>?".  SmartText variables can also be used for status
  1349.     line  reports in menus, showing such things as security, minutes remaining,
  1350.     and current time.
  1351.  
  1352.  
  1353.  
  1354.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-22
  1355.  
  1356.  
  1357.     To utilize  RBBS-PC's SmartText files,  CONFIG parameter 17 must  be set to
  1358.     the  decimal value of a delineation character  that the text editor used by
  1359.     the  SysOp can  handle.    The  character  you  select  should  have  three
  1360.     characteristics:
  1361.  
  1362.          1.   It should be visible on the screen and when printed.  This allows
  1363.               the SysOp to see where the control sequence is when designing the
  1364.               text files to be used as SmartText files.
  1365.  
  1366.          2.   It  should not be  a character that  might be used  for any other
  1367.               purpose in  the text files.   The character can still  be used in
  1368.               text  files,  but  the  chances  are  slight  that  RBBS-PC  will
  1369.               interpret the character as a SmartText sequence.
  1370.  
  1371.          3.   It  should not  be a  character that  might be  interpreted, when
  1372.               printed, as being a printer command (i.e. start double spacing).
  1373.  
  1374.       IMPORTANT:   While RBBS-PC  currently allows you to  select the SmartText
  1375.                    character, we STRONGLY suggest you use the default character
  1376.                    (the { character, decimal 123).  Future versions of  RBBS-PC
  1377.                    will  no doubt  rely heavily  on standard SmartText,  and as
  1378.                    such  will  probably NO  LONGER  allow  you to  change  this
  1379.                    character.
  1380.  
  1381.     CONFIG  parameter 17  can  have any  value  between 0  and 255.    If 0  is
  1382.     selected, RBBS-PC's SmartText capability will be turned off.
  1383.  
  1384.     A RBBS-PC SmartText control sequence consists of the control character that
  1385.     was  selected  in  CONFIG parameter  17  followed  by  a SmartText  double-
  1386.     character  command.   These  SmartText  double-character  commands MUST  be
  1387.     entered  as  upper case  characters!    There are  two  kinds of  SmartText
  1388.     variables:    those which  substitute text,  and  others which  control how
  1389.     substitution is done.  The commands are:
  1390.  
  1391.     COMMAND   NAME                MEANING
  1392.  
  1393.      BD  "Bytes Downloaded"  Displays the bytes downloaded today.
  1394.      BN  "BBS Name"          Displays the name of the BBS.
  1395.      CS  "Clear Screen"      Overrides    RBBS-PC's   automatic  screen   depth
  1396.                              management  so  that   the  next  "Press Enter  to
  1397.                              Continue" will not come halfway through a page.
  1398.      CT  "City/state"        Displays the caller's city & state.
  1399.      C0  "Color 0"           Resets color to the user's selection for text.
  1400.      C1  "Color 1"           Changes   color  to   the  user's   selection  for
  1401.                              Foreground Color One.
  1402.      C2  "Color 2"           Changes   color  to   the  user's   selection  for
  1403.                              Foreground Color Two.
  1404.      C3  "Color 3"           Changes   color  to   the  user's   selection  for
  1405.                              Foreground Color Three.
  1406.      C4  "Color 4"           Changes   color  to   the  user's   selection  for
  1407.                              Foreground Color Four.
  1408.      DB  "Dnld (tot) Bytes"  Inserts the total number of bytes ever  downloaded
  1409.                              by the caller.
  1410.      DD  "Downloads Today"   Inserts  the total  number of files  downloaded by
  1411.                              the caller today.
  1412.      DL  "DownLoads"         Inserts the  total number of files ever downloaded
  1413.                              by the caller.
  1414.      DT  "Date"              Inserts the  current  date, MM-DD-YYYY,  into  the
  1415.                              text file.
  1416.  
  1417.  
  1418.  
  1419.     PLANNING YOUR USER INTERFACE                                           7-23
  1420.  
  1421.  
  1422.      FI  "FileName"          Inserts current work Filename into the text file
  1423.      FN  "First Name"        Inserts the user's FIRST NAME into the text file.
  1424.      FS  "First Name SySop"  Inserts the SysOp's FIRST NAME into the text file.
  1425.      LN  "Last Name"         Inserts the user's LAST NAME into the text file.
  1426.      LS  "Last Name SysOp"   Inserts the SysOp's LAST NAME into the text file.
  1427.      ND  "Node Number"       Inserts the RBBS-PC Node Number for this node.
  1428.      NS  "Non Stop"          This   causes the rest  of the current  file to be
  1429.                              displayed in  RBBS-PC's  "none stop"  mode.   Page
  1430.                              breaks will be ignored following a  NS command.
  1431.      PB  "Page Break"        Causes   RBBS-PC   page   break   message,   "MORE
  1432.                              (Y/N/NS/A)"  or the    "PRESS  ENTER.." prompt  to
  1433.                              appear after the line is printed.
  1434.      RP  "Reg Period"        Inserts  the  number of  days in  the registration
  1435.                              period.
  1436.      RR  "Reg Remaining"     Displays  the  days   remaining  in  the  caller's
  1437.                              registration period.
  1438.      SL  "Security Level"    Inserts the user's current security level into the
  1439.                              text file.
  1440.      TE  "Time Elapsed"      Inserts  the user's  elapsed session  time (hh:mm)
  1441.                              into the text file.
  1442.      TM  "Time"              Inserts the time (hh:mm AM/PM) into the text file.
  1443.      TN  "Trim NO"           Substitute as is (the default)
  1444.      TY  "Trim YES"          Remove leading and trailing spaces first
  1445.          Note:   a setting  for trimming remains  in effect until  another trim
  1446.          command is encountered.
  1447.      TR  "Time Remaining"    Inserts  the  number of minutes left in the user's
  1448.                              session into  the text file.
  1449.      UB  "Upload Bytes"      Displays the total number  of bytes ever  uploaded
  1450.                              by the user.
  1451.      UL  "UpLoads"           Displays the total number of file ever uploaded by
  1452.                              the user.
  1453.      VN  "Overlay NO"        Insert into the text file (the default).
  1454.      VY  "Overlay YES"       Overlay into the text file (do not change length)
  1455.          Note:  an overlay setting remains in effect until explicitly replaced.
  1456.  
  1457.     When  designing SmartText files, each  SysOp should take  into account that
  1458.     the some of the SmartText commands (i.e. the user's name) may significantly
  1459.     extend the length  of a line.  It is important that this line elongation be
  1460.     taken into consideration so that, when the actual text substitution occurs,
  1461.     the line seen by the caller does not exceed 80 characters.
  1462.  
  1463.     What follows is an example of a SmartText file that demonstrates how all of
  1464.     the  above commands  might be  used.   The following  example assumes  that
  1465.     CONFIG parameter 17 has been set to the decimal value 123 for the SmartText
  1466.     delineation character -- {.
  1467.  
  1468.                    Introducing...{C1SmartText!{C0
  1469.  
  1470.          RBBS-PC allows  the SysOp to customize  the text seen by  each caller.
  1471.          For  instance, if the  SysOp wanted to  make sure  this message didn't
  1472.          scroll off the screen, he could pause the display like this:
  1473.          {PB
  1474.  
  1475.          Or, the SysOp may want to show the caller that today's date is {DT and
  1476.          the time  is  {TM.   The SysOp  may even  want to  include a  personal
  1477.          greeting to {FN {LN.
  1478.  
  1479.  
  1480.  
  1481.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-24
  1482.  
  1483.  
  1484.          The  SysOp can tell  the caller that  their security level  is {SL and
  1485.          that they have been on-line for {TE, and have {TR minutes left in this
  1486.          session.
  1487.  
  1488.     This  kind  of  capability  illustrates RBBS-PC's  on-going  commitment  to
  1489.     nurturing each SysOp's creativity and avoiding the dogmatic.
  1490.  
  1491.     7.10 "Colorizing" the RBBS-PC User Interface
  1492.     --------------------------------------------
  1493.     "Colorization" refers to the utilization of color within RBBS-PC text files
  1494.     and prompts.  RBBS-PC has long supported graphics versions of external text
  1495.     files,  and  is even  distributed with  graphics  menus.   RBBS-PC supports
  1496.     "colorization" as follows:
  1497.  
  1498.      1) In files shown to the callers including:
  1499.               All menus,
  1500.               All bulletins,
  1501.               The Welcome file,
  1502.               The file for new users,
  1503.               All on-line help files,
  1504.               Standard file directories, and
  1505.               FMS file directories (see item 6 below).
  1506.  
  1507.      2) Via highlighted text
  1508.               in searches of messages,
  1509.               in searches of files,
  1510.               in announcing new personal mail waiting,
  1511.               for locked out users, and
  1512.               the SysOp user maintenance (function 5).
  1513.  
  1514.     Highlighting   supports  a   limited  but   extremely  functional   use  of
  1515.     colorization  - to make it easy for the  caller to spot significant bits of
  1516.     text on a screen.
  1517.  
  1518.      3) Within the Programmable user interface (PUI).
  1519.     The PUI file  can have graphics versions  just like text  files.  The  file
  1520.     XMAIN.PUI  that  was used  in  the  example in  section  7.6.2  can have  a
  1521.     graphic's  equivalent  named  XMAING.PUI   and  a  color  equivalent  named
  1522.     XMAINC.PUI.  Color codes can be embedded  in the prompts in the PUI as well
  1523.     as external text files.   Each SysOp has total freedom to  colorize prompts
  1524.     as well as menus.
  1525.  
  1526.      4) Within text internal to RBBS-PC.
  1527.     This  applies to  standard  (non-PUI) prompts,  such  as the  main  command
  1528.     prompt,  and to formatted reports, like  the message scan and message read.
  1529.     This  type of "colorization" is controlled by whether highlighting has been
  1530.     turned on in CONFIG.
  1531.  
  1532.      5) Within RBBS-PC's "short" prompts.
  1533.     Caller foreground color 4 is used to  mark the commands the user can  type.
  1534.     Emphasis is used to mark the default selection.  This colorization is based
  1535.     on a scan of the text to be printed:
  1536.  
  1537.          [...] :   will be highlighted (default answer)
  1538.          (xxx) :   will be  put in foreground color 4 (text to type in): if xxx
  1539.                    is not longer than 2 characters and is in caps
  1540.          <...> :   will be put in  foreground color 4 (collective choices)  and
  1541.                    if  there  are  words  before   this,  the  first  will  use
  1542.                    foreground 1 and the second, foreground 2.
  1543.  
  1544.  
  1545.  
  1546.     PLANNING YOUR USER INTERFACE                                           7-25
  1547.  
  1548.  
  1549.     "Short" prompts  colorization  applies to  ALL  text displayed  by  RBBS-PC
  1550.     before an answer is expected.  For example, by using the above conventions,
  1551.     questionnaires  can   be  colorized.     This  is  controlled   by  whether
  1552.     highlighting is on.
  1553.  
  1554.      6) Within FMS file directories.
  1555.     The "colorization"  of the FMS file directories is based on the four colors
  1556.     specified  in CONFIG  and is controlled  by whether  or not  the caller has
  1557.     selected to be in color graphics mode or not.
  1558.  
  1559.     There are two extremes on the use of color: use none or use it everywhere.
  1560.  
  1561.     By using no colorization, RBBS-PC's performance is optimized.  RBBS-PC does
  1562.     not have to go through the overhead of transmitting special instructions to
  1563.     control the caller's screen.  The two chief functions of BBSs, transmission
  1564.     of  textual information and file  exchange, do not  essentially involve the
  1565.     use of color.
  1566.  
  1567.     Of  course, there  are those  who want their  RBBS-PC's visual  displays to
  1568.     convey  as much as the text or the files themselves (i.e. the message is in
  1569.     the medium).   These are  the SysOps would  elect to use  color everywhere.
  1570.     With the use of color, plain text begins to look drab and uninteresting and
  1571.     attention  tends to  focus on the  colorized text.   For  this reason, some
  1572.     SysOps find it difficult to use color in some places and not in others.
  1573.  
  1574.     Colorization  is implemented  in RBBS-PC  with ANSI  display commands.   In
  1575.     order for a caller to see the colors as RBBS-PC displays them, the terminal
  1576.     emulator  used by the  caller MUST  be ANSI-compliant.   CONFIG  allows the
  1577.     SysOp to activate and  customize colorization on screen 17,  "RBBS-PC Color
  1578.     Parameters".
  1579.  
  1580.      1)  Use CONFIG's parameter 321 to put in a string for turning EMPHASIS on.
  1581.          The  recommendation   is  a   bright  foreground  on   red  background
  1582.          ("[27][1;41m").
  1583.  
  1584.      2)  Use CONFIG's parameter 322 to set the string for normal text.  This is
  1585.          the  general default  color and  is used  to turn  off emphasis.   The
  1586.          recommended color is amber (normal yellow) ("[27][0;33m").
  1587.  
  1588.      3)  Use parameter  323, 324, 325 and 326 of CONFIG  to set the four caller
  1589.          foreground colors.  CONFIG uses natural language phrases to set these,
  1590.          so it is very easy.  The recommendation, in order, is:
  1591.  
  1592.               bright green,
  1593.               bright yellow,
  1594.               bright purple, and
  1595.               bright cyan.
  1596.  
  1597.     These colors are all used in the message header and general command prompt.
  1598.     Foreground 4 is used to highlight the commands the caller actually needs to
  1599.     type in to select that option.
  1600.  
  1601.     No  colors will be displayed if these  parameters are set to empty strings.
  1602.     Callers can  turn off the colorization  simply by going into  Utilities and
  1603.     T)oggle H)ighlite  to "off".  The default in RBBS-PC is for colorization to
  1604.     be OFF.
  1605.  
  1606.  
  1607.  
  1608.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-26
  1609.  
  1610.  
  1611.     Colorization is  based on the  ANSI standard.   Special codes  are sent  by
  1612.     RBBS-PC to  the  callers system,  which  must then  be  interpreted by  the
  1613.     caller's communications software.
  1614.  
  1615.     7.11 RBBS-PC's Automatic Operator Page Option
  1616.     ---------------------------------------------
  1617.     RBBS-PC  will "automatically page" the SysOp whenever a specified caller or
  1618.     group of callers logs on  to RBBS-PC or joins a specific  "sub-board".  The
  1619.     selection criteria  can be  a specific caller's  name, a range  of security
  1620.     levels, or  whether the  caller is  a new  user.   A SysOp may  wish to  be
  1621.     notified for any number of reasons including:
  1622.  
  1623.        - A caller has been causing  trouble on the bulletin board and  needs to
  1624.          be monitored.
  1625.        - The SysOp wants,  for security  reasons, to be  notified when  anybody
  1626.          logs on with a SysOp security level.
  1627.        - The SysOp wants to chat with a friend but does not want to continually
  1628.          monitor RBBS-PC's activity.
  1629.  
  1630.     AutoPage  is  controlled  by  a  file whose  name  is  specified  in CONFIG
  1631.     parameter 18 (the default name is AUTOPAGE.DEF).   Each line in the file is
  1632.     a separate AutoPage command.   The line contains 4 parameters  separated by
  1633.     commas.  The format is
  1634.  
  1635.          <condition>,<notify caller?>,<# of times>,<music>
  1636.  
  1637.          <condition>         Can  be  a NAME  enclosed  in  quotes, the  string
  1638.                              "NEWUSER", or  a security level range specified in
  1639.                              the format
  1640.  
  1641.                                   /<min sec>/<max sec>
  1642.  
  1643.                              where:
  1644.  
  1645.                                   <min sec> is the minimum security level
  1646.                                   <max sec> is the maximum security level
  1647.  
  1648.          <notify caller?>    Is "N" if the  caller also is to be  notified that
  1649.                              the SysOp  has been notified when  the caller logs
  1650.                              on.  Anything else means  the caller will not know
  1651.                              that the SysOp has been paged automatically.
  1652.  
  1653.          <# of times>        Is  the number of times that the PC's speaker will
  1654.                              be sounded.
  1655.  
  1656.          <music>             Is a BASIC music  command to be used instead  of a
  1657.                              beep.   If  nothing is specified,  a beep  will be
  1658.                              used.
  1659.  
  1660.     Warning:  on some PC's the playing  of music produces "out of string  space
  1661.     errors".   Test any music before using.   Beeps always work fine.
  1662.  
  1663.     Examples:
  1664.  
  1665.     "SEXY DEVIL",,1,L4EDC    AutoPage when  a caller named SEXY  DEVIL logs on,
  1666.                              do not notify the caller, and play "L4EDC".
  1667.  
  1668.     "GREGG SNYDER",N,2,      AutoPage  when GREGG  SNYDER logs  on, notify  the
  1669.                              caller, and beep the speaker twice.
  1670.  
  1671.  
  1672.  
  1673.     PLANNING YOUR USER INTERFACE                                           7-27
  1674.  
  1675.  
  1676.     "NEWUSER",,1,            AutoPage  when  any new  caller  logs  on, do  not
  1677.                              notify the caller, and beep the speaker once.
  1678.  
  1679.     /10/12,N,2,              AutoPage when anyone with  security 10 through 12,
  1680.                              inclusive, logs  on, let them know  that the SysOp
  1681.                              wants to be notified that they are on, and to beep
  1682.                              the Speaker twice.
  1683.  
  1684.     The status line at the bottom of the RBBS-PC screen will read "AP!" for the
  1685.     duration of the  caller's session  if RBBS-PC has  automatically paged  the
  1686.     SysOp.  This allows the SysOp to know that the AutoPage took place, even if
  1687.     the SysOp was not present at the beginning of the call.
  1688.  
  1689.     If the  caller triggers more than one AutoPage command, the first condition
  1690.     encountered will be used.
  1691.  
  1692.     Since  each "sub-board"  can have  a different  AutoPage command  file, the
  1693.     SysOp has the option to be automatically paged based on  different criteria
  1694.     for each "sub-board".
  1695.  
  1696.     7.12 Enhancing the File View Function
  1697.     -------------------------------------
  1698.     Within the File Subsystem of RBBS-PC the V)iew function,  allows the caller
  1699.     to get a list of files that  are "archived" inside a single file.   RBBS-PC
  1700.     supports  .ARC, .LZH,  .PAK, and .ZIP  compression formats, as  well as ANY
  1701.     format using SysOp-installed external procedures.
  1702.  
  1703.     RBBS-PC  assumes  that  the  file  extension  will  identify  the  type  of
  1704.     compression.   Hence, the SysOp can install  a View function for files with
  1705.     extension ".XYZ".   All the SysOp must do is put  a .BAT file with the name
  1706.     "Vxyz.BAT" on the same disk and  path specified for COMMAND.COM via  CONFIG
  1707.     parameter 105.   If  such  a file  is present,  RBBS-PC will  shell to  the
  1708.     command  in Vxyz.BAT  whenever a  caller asks  to V)iew  any file  with the
  1709.     extension .XYZ.   SHELLing requires  extra system RAM  beyond what  RBBS-PC
  1710.     uses.  If your system  has little or no free memory, you may  be limited to
  1711.     using the internal V)iew feature of RBBS-PC.
  1712.  
  1713.     RBBS-PC includes the following files for external View support:
  1714.  
  1715.          ARCVIEW.COM    Compiled C program for  view of DWC, PAK, ZOO,  and ARC
  1716.                         files.  Used in VDWC.BAT, VZOO.BAT.
  1717.  
  1718.          VDWC.BAT       Processor for DWC files
  1719.          VZOO.BAT       Processor for ZOO files
  1720.  
  1721.     Each BAT file contains in it:
  1722.  
  1723.          ARCVIEW [1] > [2]
  1724.  
  1725.     RBBS-PC will SHELL to the above program  (not to the BAT file) after  first
  1726.     substituting the name of  the file to be listed  for "[1]" and the  name of
  1727.     the file to place the results of the listing for "[2]".  The ">" is the DOS
  1728.     "redirect" function,  which causes  the output  to be  placed  in the  file
  1729.     instead of on the local screen.
  1730.  
  1731.     The  file specified in [2] is named "NODE?WRK" when the wildcard "?" is the
  1732.     node id (1,2,3,...).
  1733.  
  1734.  
  1735.  
  1736.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-28
  1737.  
  1738.  
  1739.     How to Implement Your Own View function
  1740.     ---------------------------------------
  1741.     Your view program must have a way to receive from RBBS
  1742.  
  1743.        - the name of the file to list
  1744.        - the name of the file to write the listing to.
  1745.  
  1746.     RBBS-PC will interface with  your program in two different  ways, depending
  1747.     on how many lines your BAT file contains.
  1748.  
  1749.     If the BAT file contains exactly 1  line, RBBS-PC will shell to the line in
  1750.     the BAT file and not to the BAT file itself.  RBBS-PC will dynamically scan
  1751.     for "[1]" and "[2]"  in the line and substitute the names of the file to be
  1752.     listed and the file to write the results to, respectively.  Everything else
  1753.     will be left intact.
  1754.  
  1755.     If the BAT  file contains more than one line, RBBS-PC will shell to the BAT
  1756.     file, passing as command line parameters the  name of the file to list, and
  1757.     the name of the results file.
  1758.  
  1759.     For example, the following BAT file could be used:
  1760.  
  1761.          ECHO OFF
  1762.          ECHO %1 >> VIEW.LOG
  1763.          ARCVIEW %1 > %2
  1764.          ECHO ON
  1765.  
  1766.     The statement  "ECHO  %1 >>  VIEW.LOG"  will create  a  list of  all  files
  1767.     selected  for view.   ">>" means  to append  the view file  name to  a file
  1768.     called "VIEW.LOG".
  1769.  
  1770.     Using ZIPTV
  1771.     -----------
  1772.  
  1773.     Ziptv  is a program distributed by Samuel  H. Smith which supports not only
  1774.     View, but the ability to list any file inside  of a ZIP file, thus allowing
  1775.     users to view documentation before  downloading a file.   Many  SysOps will
  1776.     want to install ZIPTV to replace the internal RBBS-PC View function.  To do
  1777.     so, create a VZIP.BAT as follows:
  1778.  
  1779.          DEL %2
  1780.          <path>ZIPTV -P%3 %1
  1781.  
  1782.     Where <path> is the drive and subdirectory where you have placed ZIPTV.EXE.
  1783.  
  1784.     7.13 Bulletins and News
  1785.     -----------------------
  1786.     RBBS-PC has  very powerful and  flexible features for  broadcasting system-
  1787.     wide information to  callers.   The following table  describes the  various
  1788.     NEWS options:
  1789.  
  1790.  
  1791.  
  1792.     PLANNING YOUR USER INTERFACE                                           7-29
  1793.  
  1794.  
  1795.     ┌───────────────────────────┬─────────────────────────────────────────────┐
  1796.     │ When the caller will see  │        Which file will the caller see       │
  1797.     │         the news          │                                             │
  1798.     ├───────────────────────────┼─────────────────────────────────────────────┤
  1799.     │Every time the caller logs │The file PRELOG is displayed before callers  │
  1800.     │on.                        │are asked their names.  This information     │
  1801.     │                           │should be kept very brief.                   │
  1802.     ├───────────────────────────┼─────────────────────────────────────────────┤
  1803.     │Only when a NEW USER logs  │The file NEWUSER is shown to new users only  │
  1804.     │on.                        │the first time they log on.                  │
  1805.     ├───────────────────────────┼─────────────────────────────────────────────┤
  1806.     │On every call, after the   │The file WELCOME is displayed after a        │
  1807.     │caller logs on.            │successful logon.  For graphic and color     │
  1808.     │                           │versions of this file, see section 6.3.      │
  1809.     ├───────────────────────────┼─────────────────────────────────────────────┤
  1810.     │Only when the SysOp has    │The NEWS file is displayed if the date of    │
  1811.     │updated information since  │last log on is the same or earlier than the  │
  1812.     │the last time the caller   │date of the news file.  The news file also   │
  1813.     │was on the BBS.            │can be read by using the "B N" command       │
  1814.     │                           │(Bulletin News).                             │
  1815.     ├───────────────────────────┼─────────────────────────────────────────────┤
  1816.     │Every time the caller logs │The logoff questionnaire, EPILOG.DEF is      │
  1817.     │off.                       │processed at logoff, and can be used to      │
  1818.     │                           │display news at this time.  See section 19.  │
  1819.     ├───────────────────────────┼─────────────────────────────────────────────┤
  1820.     │Available on request by    │The RBBS-PC general Bulletin files.          │
  1821.     │the caller.                │                                             │
  1822.     └───────────────────────────┴─────────────────────────────────────────────┘
  1823.  
  1824.     General Bulletin Files
  1825.     ----------------------
  1826.     General  bulletins are text files prepared by  the SysOp that can be viewed
  1827.     by  the callers when they first log on,  or at any time during the caller's
  1828.     session.   To configure bulletins, you  must first decide if  you will used
  1829.     NUMBERED  bulletins, NAMED bulletins, or both.  The only difference between
  1830.     numbered and named bulletins is in how RBBS-PC scans for new bulletins when
  1831.     a caller logs on.  With numbered bulletins ONLY, RBBS-PC uses the number of
  1832.     bulletins  specified in CONFIG parameter 62 to  find new bulletins.  If the
  1833.     SysOp uses NAMED bulletins, each bulletin must be identified to RBBS-PC (in
  1834.     the file BULLET.FCK) in order to scan for new bulletins.
  1835.  
  1836.     To create a bulletin, use CONFIG parameter 61 to  set the location and name
  1837.     of the  bulletin menu, and set parameter 63 to the desired bulletin prefix.
  1838.     If you are using numbered bulletins, also set parameter 62 to the number of
  1839.     bulletins.
  1840.  
  1841.     Ex:  Set parameter 61 to: C:\RBBS\BULLETIN\BMAIN.MNU
  1842.          Set parameter 63 to: B
  1843.  
  1844.     When RBBS-PC looks for bulletins, it will use parameter 61 for the location
  1845.     of each bulletin, and  parameter 63 to build the  file name.  If  you would
  1846.     like   a  bulletin   named   TEST,  RBBS-PC   will   look  for   the   file
  1847.     C:\RBBS\BULLETIN\BTEST.
  1848.  
  1849.     Any TEXT editor can be used to create bulletins.   The bulletin can contain
  1850.     ASCII text,  extended  ASCII  graphics,  or ANSI  color.    By  naming  the
  1851.     bulletins  properly,  RBBS-PC's graphic  support  will  display the  proper
  1852.     bulletin to the caller (e.g. BTESTC. would be the COLOR version of bulletin
  1853.     TEST).  See section 6.3 for details.
  1854.  
  1855.  
  1856.  
  1857.     RBBS-PC 17.3A            TECHNICAL REFERENCE MANUAL                    7-30
  1858.  
  1859.  
  1860.     The bulletin menu defined in  CONFIG parameter 61 should contain a  list of
  1861.     available  bulletins.   The  .MNU  extension  activates RBBS-PC's  sub-menu
  1862.     feature (see section 7.7).
  1863.  
  1864.     If only numbered bulletins  are used, RBBS-PC will be able  to scan for new
  1865.     bulletins automatically (as long  as parameter 62 has the  proper setting).
  1866.     For  named bulletins, you  must create a  list of bulletins  for RBBS-PC to
  1867.     scan.  The list should be in the file <prefix>.FCK in the same directory as
  1868.     all the bulletins.  The <prefix> is what is specified in parameter 63.   In
  1869.     our example,  this file would  be called  B.FCK.  Each  bulletin should  be
  1870.     listed, without the prefix, one per line.  Ex:
  1871.  
  1872.          TEST
  1873.          1
  1874.          2
  1875.          RBBS-PC
  1876.  
  1877.     would check the date of the files BTEST, B1, B2 and BRBBS-PC.  Note that B1
  1878.     and B2  are  considered  Numbered bulletins,  but  if B.FCK  is  used,  ALL
  1879.     bulletins are considered Named bulletins.
  1880.  
  1881.     News Bulletin File
  1882.     ------------------
  1883.     The NEWS  file is a special  bulletin that is automatically  displayed to a
  1884.     caller at  login if  it has  been updated since  his last  call.   The NEWS
  1885.     bulletin  is NOT  located with the  general bulletin  files.   It should be
  1886.     placed in the  same directory as the  WELCOME file.   The name of the  NEWS
  1887.     file  is <conference>.NWS.   The <conference>  is the  name of  the RBBS-PC
  1888.     conference to  which the news belongs (each  conference can have a separate
  1889.     news  file).   The MAIN  news file,  shown  to callers  at login,  is named
  1890.     MAIN.NWS.  News files can support color and graphics (see section 6.3).
  1891.  
  1892.